////////////////////////////////////////////////////////////////////////////////
/*! \file
 * \brief The interface file for the time manager in Lynx.
 *
 * The time manager gives access to time related functions.
 *
 * \author Ivo Wingelaar
 * \date 2011
 * \version 0.0.1
 * \copyright GNU Lesser General Public License v3
 */
////////////////////////////////////////////////////////////////////////////////

#ifndef __LYNX_TIME_MANAGER_HPP_INCLUDED__
#define __LYNX_TIME_MANAGER_HPP_INCLUDED__

////////////////////////////////////////////////////////////////////////////////
// Headers
////////////////////////////////////////////////////////////////////////////////
#include "LynxConfig.hpp"

namespace Lynx
{

////////////////////////////////////////////////////////////////////////////////
//! An interface that provides access to time-related functions.
/*!
 *
 */
class TimeManager : public virtual Myth::ReferenceCounter
{
public:
    ////////////////////////////////////////////////////////////////////////////
    //! \brief Returns the real time.
    /*!
     * Using this clock you can accurately measure the difference between two
     * points in time.
     *
     * \return The real time in milliseconds.
     *
     * \note The exact value depends on the implementation, but is guarenteed to
     *       be a taken from a high-res clock and is also monotonic (never will
     *       it return the same value twice).
     */
    virtual uint32_t get_real_time(void) const = 0;

    ////////////////////////////////////////////////////////////////////////////
    //! \brief Returns virtual time.
    /*!
     * The values returned by this function depend on the speed set by
     * set_speed. Using set_speed you can manipulate the speed of the virtual
     * clock to make it run faster or slower than the real clock.
     *
     * \return The virtual time in milliseconds.
     *
     * \note The exact value depends on the implementation, but is guarenteed to
     *       be a taken from a high-res clock.
     */
    virtual uint32_t get_virtual_time(void) const = 0;

    ////////////////////////////////////////////////////////////////////////////
    //! \brief Sets the virtual time.
    /*!
     * You can specify the current value of the virtual clock with this.
     *
     * \param[in] time The value you want the virtual clock to have.
     */
    virtual void set_virtual_time(uint32_t time) = 0;

    ////////////////////////////////////////////////////////////////////////////
    //! \brief Returns the speed value of the virtual clock.
    /*!
     * The speed is the factor with which the virtual clock is running faster or
     * slower than the real clock.
     *
     * \return The value of speed multiplier of the virtual clock.
     */
    virtual float get_virtual_speed(void) const = 0;

    ////////////////////////////////////////////////////////////////////////////
    //! \brief Sets the speed of the virtual clock.
    /*!
     * The speed is the factor with which the virtual clock is running faster or
     * slower than the real clock.
     *
     * \param[in] speed The value you want the speed multiplier of the virtual
     *                  clock to have.
     */
    virtual void set_virtual_speed(float speed = 1.0f) = 0;

    ////////////////////////////////////////////////////////////////////////////
    //! \brief Stops the virtual clock.
    /*!
     * The clock is reference counted so you must make sure that everything that
     * calls stop also calls start, otherwise the virtual clock may not start
     * correctly again.
     */
    virtual void stop_virtual_clock(void) = 0;

    ////////////////////////////////////////////////////////////////////////////
    //! \brief Starts the virtual clock.
    /*!
     * See stop_virtual_clock for notes on the behavior of this function.
     */
    virtual void start_virtual_clock(void) = 0;

    ////////////////////////////////////////////////////////////////////////////
    //! \brief Returns if the clock if currently stopped.
    /*!
     * \return True if the clock is currently stopped, false if not.
     */
    virtual bool is_virtual_clock_stopped(void) const = 0;
};

} // namespace Lynx

#endif // __LYNX_TIME_MANAGER_HPP_INCLUDED__

